ATS Bus uses NServiceBus as its service bus framework. It's configured using ATS Bus Cockpit which allows the user to setup NserviceBus’s persistence, transport, serialization and recoverability.
Make sure that the settings are configured properly before starting a bus stop as the setup will apply to all the bus stops.
ATS Bus uses safe NServiceBus settings but the Particular ServiceControl hostname must be updated before starting the bus stops.
To monitor traffic on NServiceBus you can use ServiceInsight, ServicePulse and ATS Bus Monitor.
In Cockpit select the General tab.
Click NServiceBus.
The NServiceBus dialog opens. Allowing you to configure settings for all bus stops.
NServiceBus supports multiple persistence (https://docs.particular.net/persistence/) where ATS Bus supports the RavenDB and NHibernate persistence. Best practice is to install the persistence (RavenDB or SQL database) on the same node as the bus stop to prevent issues when the network connection fails.
The persistence settings configured in this section are applied to all bus stops. When using a central database (RavenDB or MS SQL), use the hostname of the database server, when using a local instance (side by side with the bus stop), use localhost as the hostname of the database server.
RavenDB: This persistence requires a RavenDB 3.5 instance, the persistence parameter of which, has the following format:
URL = http://<computername>:<portnumber>
For example
URL = http://localhost:8084
NHibernate: This persistence requires an MS SQL Server / MS SQL Express database installed on the same node as the bus stop or on a central server. A LocalDB instance can also be used and should be installed on the same host as the bus stop. The persistence parameter is a connection string with the following format:
Data Source=server\instance;Database=PersistenceDatabase;User Id=LoginName;Password=LoginPassword;
Where:
Data Source: The instance that hosts the database.
Database: The name of the database. The database must be created before the bus stop is started. The bus stop does not create the database like RavenDB does.
User Id: The database login account.
Password: The password belonging to the login account.
Microsoft SQL: This persistence requires an MS SQL Server / MS SQL Express database installed on the same node as the bus stop or on a central server. The persistence parameter is a connection string with the following format:
Data Source=server\instance;Database=PersistenceDatabase;User Id=LoginName;Password=LoginPassword;
Where
Data Source: The instance that hosts the database.
Database: The name of the database, this can be an ATS Bus configuration database or a new one. The database must be created before the bus stop is started. The bus stop does not create the database like RavenDB does.
User Id: The database login account.
Password: The password belonging to the login account.
Oracle: This persistence requires an Oracle database. The persistence paramaters is a connection string with the following format:
User Id=LoginName;Password=LoginPassword; Enlist=false;Data Source = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = hostname of server)(PORT = Port as configured,default-1521))) (CONNECT_DATA = (SERVICE_NAME=service name as configured,default-orcl)))
where
User ID: The database login account
Password: The password belonging to the login account.
Host: The hostname of the server.
Port: The communication port used to contact the server.
ATS Bus supports the following NServiceBus transports:
MSMQ:A connection string is not required. More information about NServiceBus and MSMQ can be found here.
RabbitMQ: This is a broker based queueing solution. It requires a connection string. The connection string needs to comply with the following format:
host=<hostname>;UserName=<user>;Password=<password>;UseTls=true;CertPath=c:\<cert_directory>\<certname.p12>;CertPassphrase=<cert_password>
Where:
Host: the server where RabbitMQ is installed.
UserName: A user that can access RabbitMQ. See here for more information.
Password: The password of ‘Username’.
UseTLS: A flag indicating if the connection between the bus stop and RabbitMQ should be secured. Visit the RabbitMQ website for details about setting up TLS with RabbitMQ. Visit the Particular website for more information about this item in the connectionstring.
CertPath: The directory and filename of the client certificate.
CertPassphrase: The password that belongs to the client certificate.
MSMQ transport is a standard feature in Windows that may need to be enabled. It does not require an additional application. RabbitMQ may be needed when MSMQ is not supported or when the user wants to use TLS to encrypt the messages. Messages can be encrypted using the ‘Encrypt message body’ functionality but this makes them unreadable in ServiceInsight and that is something the user does not want. Make sure to update the transport settings in the ServiceControl instance too because they have to match the transport settings of ATS Bus.
The MSMQ message transport has a message limitation of 4MB. Larger message payloads or file attachments are currently transmitted using the NServiceBus DataBus. This transport mechanism requires a shared directory that is accessible by all bus stops. The DataBus transport parameters have a specific format:
basepath=<URN_SHARED_DRIVE>;
The ‘basepath’ is a fixed property and is used to identify the shared directory. The directory should be provided as URN: ‘\\<computername\sharedDirectory>’.
This setting defines how messages are serialized on NServiceBus. Currently JSON and XML are supported where JSON is more compact than XML. JSON is the default value.
Enabling this option encrypts the NServiceBus message body making it unreadable, even in ServiceInsight. This option does a ‘last minute’ encryption/decryption of the message content. This option is useful when running in environments where there is no Active Directory that denies unauthenticated access to MSMQ queues. This option does not add that much value when using RabbitMQ with TLS.
Configure how often and at which interval messages should be retried when transmission failed. Visit the Particular website for more information.
Immediate retries: How often to immediate retry the message.
Delayed retries: How often to repeat the immediate retries.
This is the monitoring service for NServiceBus.Visit the Particular website for more information.
Host: The hostname of the system where ServiceControl is installed.
Instance: The instance of ServiceControl to use for ATS Bus. There can be multiple instances of ServiceControl on one single host.
Make sure that ServiceControl is configured to use the same transport as is defined by ‘NServiceBus transport’. ATS Bus is not configured to support multiple transports.
ATS Bus allows OT and Archive bus stops to override the default NServiceBus Recoverability settings. It also allows plug-ins to be enabled. Each bus stop contains an NServiceBus configuration section.
Configure NServiceBus for individual bus stops
Enable heartbeat plug-in: Every 10 seconds, the bus stop will send heartbeat messages to ServiceControl once this feature is enabled. ServiceControl will keep track of these heartbeats and mark a bus stop as active if it receives them on a regular interval and will mark it as inactive if it doesn’t. ServicePulse, the NServiceBus monitoring tool, shows the active/inactive state of the bus stops. This feature is enabled by default when creating a new bus stop, it may be disabled but it is recommended to keep it enabled to allow monitor the active/inactive state of a bus stop.
More information about heartbeats can be found online here and here.
Enable metrics/monitoring: Allows bus stop throughput, processing times and other KPI’s to be monitored in Particular ServicePulse. It shows how well the bus stop is performing.
Enable message auditing: Auditing has a considerable impact on the performance of the monitoring node and the required disk space. Messages not being audited are not shown in ServiceInsight and are not stored in the ServiceControl persistence.
Enable saga auditing (not available in Archive bus stop): This plug-in enables the ‘Saga’ view in ServiceInsight. Sagas are containers that can be used by various handlers to add information. Sagas are used for long running operations such as work orders. More information about the plug-in can be found on:
More information about sagas can be found online here.
Immediate retries: How often to immediately retry the message. Remove the tick to override the default value.
Delayed retries: How often to repeat the immediate retries. Remove the tick to override the default value.
Specify which messages should not be audited by adding them to the Message Auditing Filter (not available in Archive bus stop).
Can we improve this topic?